bitkeeper revision 1.817 (405ef60cUJ4B9bY3LZWu-yP8DBid2w)

Console-HOWTO.txt:
  new file

diff --git a/.rootkeys b/.rootkeys
index c6fe3694bb008337d422481b5332f580f02c1a28..682628e2633a2867a00f2f3637a88684156bf8c1 100644 (file)
--- a/.rootkeys
+++ b/.rootkeys
@@ -6,6 +6,7 @@
 3f5ef5a24IaQasQE2tyMxrfxskMmvw README
 3f5ef5a2l4kfBYSQTUaOyyD76WROZQ README.CD
 3f69d8abYB1vMyD_QVDvzxy5Zscf1A TODO
+405ef604hIZH5pGi2uwlrlSvUMrutw docs/Console-HOWTO.txt
 3f9e7d53iC47UnlfORp9iC1vai6kWw docs/Makefile
 40083bb4LVQzRqA3ABz0__pPhGNwtA docs/VBD-HOWTO.txt
 4021053fmeFrEyPHcT8JFiDpLNgtHQ docs/Xeno-HOWTO.txt

diff --git a/docs/Console-HOWTO.txt b/docs/Console-HOWTO.txt
new file mode 100644 (file)
index 0000000..0970dce
--- /dev/null
+++ b/docs/Console-HOWTO.txt
@@ -0,0 +1,71 @@
+    New console I/O infrastructure in Xen 1.3
+    =========================================
+
+    Keir Fraser, University of Cambridge, 22nd March 2004
+
+ I thought I'd write a quick note about using the new console I/O
+ infrastructure in Xen 1.3. Significant new features compared with 1.2,
+ and with older revisions of 1.3, include:
+  - bi-directional console access
+  - log in to a Xenolinux guest OS via its virtual console
+  - a new terminal client (replaces the use of telnet in character mode)
+  - proper handling of terminal emulation
+
+Domain 0 virtual console
+------------------------
+ The virtual console for domain 0 is shared with Xen's console. For
+ example, if you specify 'console=com1' as a boot parameter to Xen,
+ then domain 0 will have bi-directional access to the primary serial
+ line. Boot-time messages can be directed to the virtual console by
+ specifying 'console=xencons0' as a boot parameter to Xenolinux.
+
+Connecting to the virtual console
+---------------------------------
+ Domain 0 console may be accessed using the supplied 'miniterm' program
+ if raw serial access is desired. If the Xen machine is connected to a
+ serial-port server, then the supplied 'xencons' program may be used to
+ connect to the appropriate TCP port on the server:
+  # xencons <server host> <server port>
+
+Logging in via virtual console
+------------------------------
+ It is possible to log in to a guest OS via its virtual console if a
+ 'getty' is running. To achieve this, a suitable device node must be
+ created, and a new line added to inittab:
+  # mkdir -p /dev/xen
+  # mknod /dev/xen/cons c 4 123
+  # echo "c:2345:respawn:/sbin/mingetty --noclear xen/cons" >>/etc/inittab
+
+ [NOTE to users in the lab -- existing Xen installations may be running
+ mingetty on /dev/console. This is incorrect behaviour! Please modify
+ such setups to run mingetty on /dev/xen/cons.]
+
+ Additionally, if you wish to allow root logins via the virtual
+ console, then 'xen/cons' must be added to the trusted tty list in
+ /etc/securettys.
+
+Virtual console for other domains
+---------------------------------
+ Every guest OS has a virtual console that is accessible via
+ 'console=xencons0' at boot time, or mingetty running on
+ /dev/xen/cons. However, domains other than domain 0 do not have access
+ to the physical serial line. Instead, their console data is sent to
+ and from a control daemon running in domain 0. When properly
+ installed, this daemon can be started from the init scripts (e.g.,
+ rc.local):
+  # /usr/sbin/xend start
+
+ Note that, when a domain is created using xc_dom_create.py, xend MUST
+ be running. If everything is set up correctly then xc_dom_create will
+ print the local TCP port to which you should connect to perform
+ console I/O. A suitable console client is provided by the Python
+ module xenctl.console_client: running this module from the command
+ line with <host> and <port> parameters will start a terminal
+ session. This module is also installed as /usr/bin/xencons, from a
+ copy in tools/misc/xencons. For example:
+  # xencons localhost 9600
+
+ An alternative to manually running a terminal client is to specify
+ '-c' to xc_dom_create.py, or add 'auto_console=True' to the defaults
+ file. This will cause xc_dom_create.py to automatically become the
+ console terminal after starting the domain.